<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Progress Percentages</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
  var popup = document.getElementById(material_id);
  popup.classList.toggle("show");
}
</script>

<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Progress Percentages' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inform7n.html">Inform7</a></li><li><a href="index.html">core</a></li><li><a href="index.html#1">Chapter 1: Control</a></li><li><b>Progress Percentages</b></li></ul></div>
<p class="purpose">This tiny section, the Lichtenstein of Inform, prints percentage of completion estimates so that the host application can intercept them and update its graphical progress bar.</p>

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>Clearly we can only estimate how far Inform has progressed. While we could in
principle measure the number of CPU-seconds it has run for, we don't know
how many more it will need. Instead, we rely on experience to suggest that
its run can be broken down into the following five stages, which a given
percentage of time spent in each stage: thus, for instance, semantic
analysis takes up about ten percent of every run in which problems do
not cause an early halt. Within each stage, we have a reasonable measure
of how far we have got: what proportion of the phrases have been compiled,
for instance, tells us how far "generating code" has got. The result is
that (if the relevant command line setting has been set, so that
<span class="extract"><span class="extract-syntax">show_progress_indicator</span></span> is true) Inform prints about thirty lines like this
one to <span class="extract"><span class="extract-syntax">stderr</span></span>:
</p>

<p class="commentary"><span class="extract"><span class="extract-syntax">++ 32% (Binding rulebooks)</span></span>
</p>

<p class="commentary">The Inform application can intercept and parse these lines to display a
progress bar with a rubric beneath it.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">; </span><span class="comment-syntax"> Produce percentage of progress messages</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ProgressBar::enable_or_disable</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">which</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax"> = </span><span class="identifier-syntax">which</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">last_progress_pc</span><span class="plain-syntax"> = -100;</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">progress_stage_from</span><span class="plain-syntax">[] = { </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">5</span><span class="plain-syntax">, </span><span class="constant-syntax">15</span><span class="plain-syntax">, </span><span class="constant-syntax">20</span><span class="plain-syntax">, </span><span class="constant-syntax">40</span><span class="plain-syntax">, </span><span class="constant-syntax">100</span><span class="plain-syntax"> };</span>
<span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">progress_stage_name</span><span class="plain-syntax">[] = {</span>
<span class="plain-syntax">    </span><span class="string-syntax">"Reading text"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="string-syntax">"Analysing sentences"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="string-syntax">"Drawing inferences"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="string-syntax">"Binding rulebooks"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="string-syntax">"Generating code"</span>
<span class="plain-syntax">};</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ProgressBar::update</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">ProgressBar::update</span></span>:<br/>What To Compile - <a href="1-wtc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stage</span><span class="plain-syntax">, </span><span class="reserved-syntax">float</span><span class="plain-syntax"> </span><span class="identifier-syntax">proportion</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">r1</span><span class="plain-syntax"> = </span><span class="identifier-syntax">progress_stage_from</span><span class="plain-syntax">[</span><span class="identifier-syntax">stage</span><span class="plain-syntax">], </span><span class="identifier-syntax">r2</span><span class="plain-syntax"> = </span><span class="identifier-syntax">progress_stage_from</span><span class="plain-syntax">[</span><span class="identifier-syntax">stage</span><span class="plain-syntax">+1];</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">pc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">r1</span><span class="plain-syntax"> + ((</span><span class="reserved-syntax">int</span><span class="plain-syntax">) (</span><span class="identifier-syntax">proportion</span><span class="plain-syntax">*(</span><span class="identifier-syntax">r2</span><span class="plain-syntax">-</span><span class="identifier-syntax">r1</span><span class="plain-syntax">)));</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pc</span><span class="plain-syntax">-</span><span class="identifier-syntax">last_progress_pc</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">3</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"++ %d%% (%s)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pc</span><span class="plain-syntax">, </span><span class="identifier-syntax">progress_stage_name</span><span class="plain-syntax">[</span><span class="identifier-syntax">stage</span><span class="plain-syntax">]);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">last_progress_pc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">pc</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ProgressBar::final_state_of_progress_bar</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">ProgressBar::final_state_of_progress_bar</span></span>:<br/>Using Problems - <a href="2-up.html#SP3_3">&#167;3.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"++ 100%% (Finishing work)\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>Finally, the following sends a pithy summary back to the app to use as
a final status indicator.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">ProgressBar::begin_outcome</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">ProgressBar::begin_outcome</span></span>:<br/>Using Problems - <a href="2-up.html#SP3_2">&#167;3.2</a>, <a href="2-up.html#SP3_3">&#167;3.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"++ Ended: "</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ProgressBar::end_outcome</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">ProgressBar::end_outcome</span></span>:<br/>Using Problems - <a href="2-up.html#SP3_2">&#167;3.2</a>, <a href="2-up.html#SP3_3">&#167;3.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">show_progress_indicator</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="1-cp2.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresscurrentchapter">1</li><li class="progresssection"><a href="1-cm.html">cm</a></li><li class="progresssection"><a href="1-cp.html">cp</a></li><li class="progresssection"><a href="1-wtc.html">wtc</a></li><li class="progresssection"><a href="1-htc.html">htc</a></li><li class="progresssection"><a href="1-cp2.html">cp2</a></li><li class="progresscurrent">pp</li><li class="progresssection"><a href="1-cs.html">cs</a></li><li class="progresssection"><a href="1-inaa.html">inaa</a></li><li class="progresssection"><a href="1-itc.html">itc</a></li><li class="progresssection"><a href="1-gtg.html">gtg</a></li><li class="progresschapter"><a href="2-up.html">2</a></li><li class="progresschapter"><a href="3-pc.html">3</a></li><li class="progressnext"><a href="1-cs.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

